home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / misc / srename / srename.doc < prev    next >
Text File  |  1999-04-19  |  61KB  |  1,609 lines
  1.  
  2. *******************************************************************************
  3.                          SRENAME 2.800  USERS MANUAL
  4.               Copyright (C) 1996-1999 Constantinos Nicolakakis
  5. *******************************************************************************
  6.  
  7.  
  8. INTRODUCTION :
  9.  
  10. The philosophy behind SRename is to give you a CLI command with relatively few,
  11. but versatile functions that can be combined in many ways to provide whatever
  12. renaming operation is needed by the user, rather than providing dozens of
  13. specialised renaming options that limit the renaming operations that can be
  14. performed, to what the programmer had in mind when he was designing the command
  15. and are difficult to remember by the user.
  16. SRename can easily replace the original Rename command but I wouldn't recommend
  17. that because SRename's behaviour is not identical to the original command.
  18. You will probably find SRename most useful at renaming a lot of filenames at
  19. once, as it supports wildcards, multiple filenames and recursion.
  20.  
  21. Some of SRename's advantages:
  22.  
  23.  * Selector-Action keyword separation that allows building specialized
  24.    functions easily.
  25.  * Total control over recursion.
  26.  * Wildcard and multiple filename support.
  27.  * Optional wildcard for directory selection in recursion.
  28.  * Can isolate selected parts of the filename for modification with the use
  29.    of the selector keywords.
  30.  * Executes multiple actions in one go.
  31.  * Performs intelligent renumbering with automatic checking for filename
  32.    clashes.
  33.  * Supports long filenames on filesystems that allow them.
  34.  * It's free.
  35.  
  36.  
  37. PROGRAM STATUS :
  38.  
  39. SRename is freeware. Permission is granted to distribute free of charge,
  40. in unchanged form, provided this documentation file is accompanied with the
  41. program.
  42. Permission is granted to include on freely distributable software libraries
  43. such as Aminet CD-ROMs.
  44. The author's permission is required if SRename is to be distributed as a part
  45. of a commercial application.
  46. Although I'm quite confident that SRename contains no major bugs, I can't
  47. guarantee that it is completely bug-free, and do not accept any responsibility
  48. of any damage this program could cause directly or indirectly.
  49.  
  50.  
  51. REQUIREMENTS :
  52.  
  53. Amiga with kickstart 2 or higher.
  54.  
  55.  
  56. TECHNICAL :
  57.  
  58. SRename is written in C++ and was compiled with SAS C 6.58. It uses C++
  59. features like object classes to achieve code reusability, memory management
  60. reliability and good program design.
  61. Memory is allocated dynamically in pages, to avoid high memory usage.
  62. Average memory usage is around 100-200 Kb when recursing through large disks
  63. or partitions.
  64. It always uses buffers when renaming more than one filename as the Ram-Disk's
  65. filesystem has a bug that makes unbuffered renaming with pattern matching
  66. problematic.
  67. SRename has been tested successfully with Enforcer and MungWall on my A4000 
  68. 060 @50 / 604e @200, kickstart 3.0, 72 MB RAM.
  69.  
  70.  
  71. INSTALLATION :
  72.  
  73. Just copy SRename to your C: directory.
  74.  
  75.  
  76. INTERFACE CHANGES/ADDITIONS :
  77.  
  78. The command interface of SRename is not 100% backwards compatible with previous
  79. versions, as some functions have been replaced by others along the way, and
  80. some improvements have been made to the command interface itself to make it
  81. more consistent and easier to use.
  82. To make it easier to upgrade to newer versions, I include a button bank for
  83. use with Directory Opus 5 or higher, that is set up to work with the latest
  84. version of SRename.
  85.  
  86. Since 2.710:
  87.  
  88. Single character mode is now automatically activated if the string given after
  89. MATCH consists of only one character. This makes the colon ':' that indicates
  90. single character mode unnecessary when matching only a single character.
  91.  
  92. Since 2.700:
  93.  
  94. LENGTH action removed. It can easily be replaced by MID <num> DELETE.
  95. Added WORD selector, supported by FROMEND, INCLSEP and WSEP.
  96.  
  97. Since 2.540:
  98.  
  99. MATCH additions: multiple match string support, single character mode, and
  100. character code mode.
  101. DELCHARS was removed as it can be replaced by MATCH :<chars> DELETE.
  102. SWAP now takes into account the PREFIX/MAIN/SUFFIX selectors, so that parts
  103. other than just the extremest can be swapped.
  104.  
  105. Since 2.520:
  106.  
  107. The TO keyword is no longer needed to perform simple renaming, so you can now
  108. type 'SRename oldname newname' to rename 'oldname' as 'newname'.
  109. The FILENAME keyword was renamed as FROM (same as the original rename command).
  110.  
  111. Since 2.510:
  112.  
  113. ICONS option was added to automatically rename .info files in single or
  114. multiple filename mode (not in wildcard mode).
  115.  
  116. Since 2.500:
  117.  
  118. New keywords:
  119.  
  120.  - DO
  121.  - SKIP
  122.  - BEFORE
  123.  - AFTER
  124.  - REVMATCH
  125.  - AT
  126.  - APPEND
  127.  - UPDATE
  128.  - UPTO
  129.  
  130. Removed keywords:
  131.  
  132.  - DELBASE (is replaced by BASENAME "")
  133.  
  134. Additional parameters were removed from keywords:
  135.  
  136.  - MATCH (moved to DO, SKIP, BEFORE, AFTER, REVMATCH)
  137.  - INSERT (moved to AT, APPEND)
  138.  - RENUMBER (moved to UPTO)
  139.  
  140. Other changes:
  141.  
  142. LEFT-RIGHT is not used anymore to set the position of the number within the
  143. basename in renumbering mode. Instead the AT and APPEND keywords are used for
  144. that purpose.
  145. The following keywords now have different full names:
  146.  - PRE is PREFIX
  147.  - SUF is SUFFIX
  148.  - LEN is LENGTH
  149. The following keywords now have abbreviations:
  150.  - PREFIX (PR)
  151.  - MAIN (MA)
  152.  - SUFFIX (SU)
  153.  - LEFT (L)
  154.  - MID (M)
  155.  - RIGHT (R)
  156.  - QUIET (Q)
  157.  
  158. Read each function's description for details about it's syntax.
  159.  
  160.  
  161. USAGE :
  162.  
  163. SRename FROM/A/M,TO=AS/K,RLEVEL=RL/N,SLEVEL=SL/N,DIRPAT=DP/K,ALLDIRS=AD/S,
  164. RECURSE=RC/S,NODIRS=ND/S,NOFILES=NF/S,ICONS=IC/S,DOT/K,WSEP=WS/K,PREFIX=PR/S,
  165. MAIN=MA/S,SUFFIX=SU/S,WORD=WD/N,FROMEND=FE/S,INCLSEP=IS/N,LEFT=L/K,MID=M/K,
  166. RIGHT=R/K,MATCH=MT/K,DO/N,SKIP=SK/N,BEFORE=BF/S,AFTER=AF/S,REVMATCH=RM/S,
  167. EXCLUDE=XC/S,EXIST=XS/S,CASESENS=CS/S,UPPER=UP/S,LOWER=LW/S,UPAFTERSPC=US/S,
  168. INSERT=IN/K,AT/N,APPEND=AP/S,UPDATE=UD/S,DELETE=DL/S,SWAP=SW/S,LSHIFT=LS/S,
  169. RSHIFT=RS/S,UNIFY=UN/S,CONV8+3=8+3/S,RENUMBER=RN/K,UPTO=UT/N,STEP=ST/N,
  170. PLACES=PL/N,INVERT=IV/S,BASENAME=BN/K,PREFIRST=PF/S,NODIROUT=NDO/S,QUIET=Q/S:
  171.  
  172.  
  173. Short description of keywords :
  174.  
  175.           FROM <string(s)> : filenames to rename, multiple can be accepted
  176.  
  177.                TO <string> : new string that replaces the selected characters,
  178.                              and/or destination path
  179.  
  180.            RLEVEL <number> : maximum level of recursion
  181.  
  182.            SLEVEL <number> : starting level of recursion
  183.  
  184.            DIRPAT <string> : match pattern for entering directories
  185.  
  186.                    ALLDIRS : make the DIRPAT pattern be used and beyond the
  187.                              starting level of recursion
  188.  
  189.                    RECURSE : sets full recursion
  190.  
  191.                     NODIRS : no directories are renamed
  192.  
  193.                    NOFILES : no files are renamed
  194.  
  195.                      ICONS : rename .info files automatically
  196.  
  197.            DOT <character> : set the separator of prefix,main,suffix
  198.  
  199.        WSEP <character(s)> : set the separator of words
  200.  
  201.                     PREFIX : operate on prefix
  202.  
  203.                       MAIN : operate on main
  204.  
  205.                     SUFFIX : operate on suffix
  206.  
  207.   WORD <number>,[<number>] : operate on specified word
  208.  
  209.                    FROMEND : select word from the end
  210.  
  211.           INCLSEP <number> : also select the word's separating chars
  212.  
  213.   LEFT <number>,[<number>] : operate on characters from the left
  214.  
  215.  MID [<number>],[<number>] : operate on characters in the middle
  216.  
  217.  RIGHT <number>,[<number>] : operate on characters from the right
  218.  
  219.             MATCH <string> : operate on part that matches the string
  220.  
  221.                DO <number> : number of matches to perform
  222.  
  223.              SKIP <number> : number of matches to skip before starting
  224.  
  225.                     BEFORE : select the characters before the matched string
  226.  
  227.                      AFTER : select the characters after the matched string
  228.  
  229.                   REVMATCH : look for matches from the end of the filename
  230.  
  231.                    EXCLUDE : invert the selection process
  232.  
  233.                      EXIST : operate on a filename component only if it exists
  234.  
  235.                   CASESENS : enable case-sensitive matching
  236.  
  237.                      UPPER : make selected characters uppercase
  238.  
  239.                      LOWER : make selected characters lowercase
  240.  
  241.                 UPAFTERSPC : make uppercase the character after a space
  242.  
  243.            INSERT <string> : insert string into the filename
  244.  
  245.                AT <number> : position from the start to insert
  246.  
  247.                     APPEND : measure insert position from the end
  248.  
  249.                     UPDATE : insert/append a string only if it does not exist
  250.                              in the specified position
  251.  
  252.                     DELETE : delete the selected characters
  253.  
  254.                       SWAP : swap the selected segments
  255.  
  256.                     LSHIFT : shift filename segments to the left
  257.  
  258.                     RSHIFT : shift filename segments to the right
  259.  
  260.                      UNIFY : unify the selected segments
  261.  
  262.                    CONV8+3 : convert to MS-DOS filename format
  263.  
  264.          RENUMBER <number> : renumber a filename sequence to start with the
  265.                              given number
  266.  
  267.              UPTO <number> : renumber up to that number
  268.  
  269.              STEP <number> : set the renumber step value
  270.  
  271.            PLACES <number> : set the renumber number-format
  272.  
  273.                     INVERT : perform inverted renumbering
  274.  
  275.          BASENAME <string> : set the renumber basename
  276.  
  277.                   PREFIRST : set the prefix segment first
  278.  
  279.                   NODIROUT : no directory name output
  280.  
  281.                      QUIET : no output at all
  282.  
  283.  
  284. A detailed description of the above keywords can be found below. Most keywords
  285. have an abbreviation which is the one in parentheses after their full name.
  286.  
  287.  
  288. *******************************************************************************
  289.                               FILE/DIR SELECTORS:
  290. *******************************************************************************
  291.  
  292. The following keywords define which files or directories will be renamed,
  293. according to their name, file or dir type, directory tree level, and the
  294. directory name that are in.
  295.  
  296.  
  297. FROM <filename(s)> :
  298. The given file(s) or dir(s) are renamed. If just a directory or volume is
  299. supplied, all its files are renamed. If instead of a filename, a pattern
  300. (wild-card) is given, only files or dirs that match this pattern will be
  301. renamed.
  302. Multiple patterns can be supplied. Note that you don't actually have to type
  303. 'FROM' in the command line.
  304.  
  305. Examples:
  306. > SRename C LW : Make C lowercase regardless of type (file or dir)
  307.  
  308. > SRename C/ LW : Make all files and dirs in C lowercase
  309.  
  310. > SRename C:d* UP : Make all files and dirs in C that begin with 'd' uppercase
  311.  
  312. -------------------------------------------------------------------------------
  313.  
  314. RLEVEL (RL) <recursion level value> :
  315. Sets the level of recursion. If this is 1, only subdirectories in the current
  316. directory will be entered.
  317. The default recursion level is 0 (no recursion).
  318.  
  319. Example:
  320. > SRename SYS:Games/a* LW RL 3 : Make all files in SYS:Games that begin with
  321. 'a' and in subdirectories up to 3 levels deep lowercase.
  322.  
  323. -------------------------------------------------------------------------------
  324.  
  325. SLEVEL (SL) <starting level value> :
  326. Sets the starting level of recursion. Files and directories in a tree level
  327. lower than the specified will not be entered. Also sets full recursion if a
  328. RLEVEL parameter is not given. The default starting level is 1.
  329. Note that the value of SLEVEL can not be greater than the value of RLEVEL.
  330.  
  331. Example:
  332. > SRename SYS: UP SL 2 : Make all filenames in SYS: uppercase, except for the
  333. filenames in the root directory.
  334.  
  335. -------------------------------------------------------------------------------
  336.  
  337. RECURSE    (RC) :
  338. Sets full recursion. All directories in the directory tree will be entered.
  339. It is overridden by RLEVEL and can also be set by ALLDIRS.
  340.  
  341. Example:
  342. > SRename SYS:Games/a* LW RC : Make all files in SYS:Games that begin with 'a'
  343. lowercase in all subdirectories.
  344.  
  345. -------------------------------------------------------------------------------
  346.  
  347. DIRPAT (DP) <wildcard pattern> :
  348. Determines which directories in a given path are to be entered to rename their
  349. contents, according to the specified pattern.
  350. This parameter implies that recursion is active, if not it sets the level of
  351. recursion to 1.
  352. Note that the DIRPAT pattern, is used only once, for the directories that exist
  353. in the directory that renaming begins.
  354. If you want the DIRPAT pattern to be used all the way when recursing, you must
  355. give the ALLDIRS keyword.
  356.  
  357. Examples:
  358. > SRename SYS:Data/*z DP project* DL SU : Remove the suffix from all the
  359. filenames in SYS:Data that end with 'z' and from the filenames in the
  360. subdirectories of SYS:Data that begin with 'project'.
  361.  
  362. > SRename SYS:Data/*z DP project* DL SU RC : Same as the previous example but
  363. acts on filenames in all subdirectories that are contained in directories
  364. that begin with 'project'.
  365.  
  366. -------------------------------------------------------------------------------
  367.  
  368. ALLDIRS (AD) :
  369. Makes the DIRPAT pattern be used with all directories that are encountered,
  370. not just with those in the starting level. A directory is entered for renaming
  371. to take place, only if it matches the DIRPAT pattern.
  372. ALLDIRS sets full recursion if a RLEVEL parameter is not given.
  373.  
  374. Examples:
  375. > SRename SYS:Data/*z DP project* DL SU AD : Remove the suffix from all
  376. the filenames in SYS:Data that end with 'z' and in all subdirectories of
  377. SYS:Data that begin with 'project'.
  378.  
  379. > SRename SYS:Data/*z DP project* DL SU RL 2 : same as the previous
  380. example but only acts on subdirectories of SYS:Data that begin with 'project'
  381. in a depth of up to 2 levels.
  382.  
  383. -------------------------------------------------------------------------------
  384.  
  385. NODIRS (ND) :
  386. Do not rename any directories. Only files are renamed.
  387.  
  388. Example:
  389. > SRename Work/Data/ UP ND : Make all the filenames in Work/Data uppercase.
  390. Directory names are not renamed.
  391.  
  392. -------------------------------------------------------------------------------
  393.  
  394. NOFILES (NF) :
  395. Do not rename any files. Only directories are renamed.
  396.  
  397. Example:
  398. > SRename Work/Data LW NF : Make all the dirnames in Work/Data lowercase.
  399. Filenames are not renamed.
  400.  
  401. Note: if both NODIRS and NOFILES are given, only NODIRS will remain active.
  402.  
  403. -------------------------------------------------------------------------------
  404.  
  405. ICONS (IC) :
  406. When in single or multiple filename mode, or in renumbering mode, the icon
  407. files (.info files) are renamed automatically even if they weren't specified
  408. in the filename list.
  409. Note that the way this option works is that the icon gets exactly the same
  410. filename that was given to the file that the icon accompanies (the icon's
  411. filename itself is not taken into account).
  412. This keyword can not be used with wildcards.
  413.  
  414. Examples:
  415. > SRename tools/lacer tools/prepcard UP IC : Make 'lacer' and 'prepcard'
  416. uppercase including their icons' filenames.
  417. output:
  418. lacer renamed as LACER
  419. lacer.info renamed as LACER.info
  420. prepcard renamed as PREPCARD
  421. prepcard.info renamed as PREPCARD.info
  422.  
  423. >SRename picture1 RN 10 IC : Renumber files from picture1 and up, including
  424. their icons.
  425. output:
  426. picture1 renamed as picture10
  427. picture1.info renamed as picture10.info
  428. picture2 renamed as picture11
  429. picture2.info renamed as picture11.info
  430. picture3 renamed as picture12
  431. picture3.info renamed as picture12.info
  432.  ....
  433.  
  434.  
  435. *******************************************************************************
  436.                   CHARACTER SELECTORS:  (in order of evaluation)
  437. *******************************************************************************
  438.  
  439. The following keywords define which parts of the filename will be affected by
  440. the action keywords that will follow. The selection can be done according to
  441. the position of the characters or the characters themselves.
  442.  
  443.  
  444. PREFIX (PR) :
  445. Select the prefix (leftmost part) for modification.
  446.  
  447. MAIN (MA) :
  448. Select the main part (middle part) for modification.
  449.  
  450. SUFFIX (SU) :
  451.  Select the suffix (rightmost part) for modification.
  452.  
  453. Specifying one of the above selectors does not cancel the others. Note that
  454. if SRename receives a filename with only two components it regards that the
  455. filename has no prefix.
  456. The prefix component is filled only if the filename has 3 or more components,
  457. or with 2 components if PREFIRST is specified, which forces prefix-main to be
  458. filled instead of main-suffix.
  459.  
  460. Here are some examples on how different filenames fill the PREFIX-MAIN-SUFFIX
  461. components:
  462.  
  463.      Filename          PREFIX          MAIN          SUFFIX
  464.  ----------------     --------       --------       --------
  465.  test              :   -empty-         test          -empty-
  466.  
  467.  001.test.pic.gif  :    001            test.pic       gif
  468.  
  469.  test.pic.gif      :    test           pic            gif
  470.  
  471.  001.test          :   -empty-         001            test
  472.  
  473.  001.test PF       :    001            test          -empty-
  474.  
  475. Examples:
  476. > SRename Work:#? SU ilbm XS : Replaces the contents of the suffix of
  477. every filename in Work: with 'ilbm', if they have a suffix.
  478.  
  479. > SRename files/backup.lzx MA UP : Makes the main component uppercase.
  480. output: backup.lzx renamed as BACKUP.lzx
  481.  
  482. > SRename mod.techno PR UP PF : Forces PREFIX to be filled before SUFFIX and
  483. makes the prefix uppercase.
  484. output: mod.techno renamed as MOD.techno
  485.  
  486. > SRename TheLastBallad.s3m SU UP : Makes the suffix uppercase.
  487. output: TheLastBallad.s3m renamed as TheLastBallad.S3M
  488.  
  489. -------------------------------------------------------------------------------
  490.  
  491. WORD (WD) <starting word number>,[number of words to select] :
  492. Select a word within the filename. A word is determined by spaces by default,
  493. unless the word separator is changed with the WSEP keyword.
  494. Words are selected from the start of the filename unless the FROMEND keyword
  495. is given.
  496. If the second parameter is also given, then consecutive words can be selected.
  497. Note that WORD is evaluated after PREFIX/MAIN/SUFFIX and before MATCH and
  498. LEFT/MID/RIGHT, so you can't select a filename part with MATCH or LEFT/MID/
  499. RIGHT and then select a word within that part, but you can select a word
  500. within PREFIX/MAIN/SUFFIX.
  501.  
  502. Examples:
  503. > SRename "screen grab of game" WD 1 UP
  504. output: screen grab of game renamed as SCREEN grab of game
  505.  
  506. > SRename "screen grab of game" WD 1,2 UP
  507. output: screen grab of game renamed as SCREEN GRAB of game
  508.  
  509. > SRename Data:Pics/ MA WD 1 UP : Makes uppercase the first word in the main
  510. part of the filename.
  511.  
  512. > SRename Data:Pics/ MA WD 1 L 1 UP : Makes uppercase the first character of
  513. the first word in the main part of the filename.
  514.  
  515. -------------------------------------------------------------------------------
  516.  
  517. FROMEND (FE) :
  518. Makes the WORD selector select words from the end of the filename.
  519.  
  520. Example:
  521. > SRename "Letter to john" WD 1 FE UP
  522. output: Letter to john renamed as Letter to JOHN
  523.  
  524. -------------------------------------------------------------------------------
  525.  
  526. INCLSEP (IS) <number> :
  527. Makes the WORD selector to include the separating characters that are left or
  528. right of the word to select. The supplied number can be 1 or 2 and designates
  529. what separating characters should be included.
  530. 1 means that the separating characters of only one side of the word will be
  531. included: the right side. If there aren't any on the right side, then the
  532. characters on the left side will be included.
  533. 2 means that the separating characters on both sides will be inluded, if they
  534. exist.
  535. This keyword has been included mainly to aid in the deleting of words.
  536. Without INCLSEP the WORD selector will select the exact word that is told to,
  537. and in case that word is to be deleted the spaces next to that word will remain.
  538.  
  539. For example:
  540. > SRename "Bin:Picture of a ship" WD 3 DL
  541. output: Picture of a ship renamed as Picture of  ship
  542.  
  543. As you see there are two spaces between 'of' and 'ship' instead of one that
  544. would be normal. If you use INCLSEP 1 you will have:
  545.  
  546. > SRename "Bin:Picture of a ship" WD 3 IS 1 DL
  547. output: Picture of a ship renamed as Picture of ship
  548.  
  549. Now the WORD selector selects 'a ' instead of 'a' for deletion.
  550.  
  551. If you use INCLSEP 2 you will have:
  552.  
  553. > SRename "Bin:Picture of a ship" WD 3 IS 2 DL
  554. output: Picture of a ship renamed as Picture ofship
  555.  
  556. Now WORD selected ' a ' for deletion.
  557.  
  558. -------------------------------------------------------------------------------
  559.  
  560. WSEP (WS) <char(s)> :
  561. Defines the word separator that will be used by the WORD selector to pick up
  562. words. This is a space character by default.
  563. This separator can be more than one character if this is really needed.
  564.  
  565. Example:
  566. > SRename Letter_to_john WD 3 UP WS _
  567. output: Letter_to_john renamed as Letter_to_JOHN
  568.  
  569. -------------------------------------------------------------------------------
  570.  
  571. MATCH (MT) [:][/]<string(s)> :
  572. Selects the characters that match the supplied string(s).
  573. If the string to match is preceded by a colon ':' then single character mode
  574. is activated and the supplied string is treated as individual characters.
  575. This mode is now used to replace the DELCHARS action.
  576. Example:
  577. > SRename Pics/ MT :[]{}()<>#@ DELETE : Remove all []{}()<>#? characters from
  578. the filenames in Pics.
  579.  
  580. If the match string begins with a slash '/' then character code mode is
  581. activated, and single or multiple comma separated ASCII codes or single
  582. characters should follow.
  583. Example:
  584. > SRename Data/ MT /42,> DELETE : Remove all '*' and '>' characters from the
  585. filenames in Data.
  586.  
  587. In this mode you can also select character ranges by supplying two characters
  588. or their ASCII codes which should be separated by a minus sign '-', or just
  589. the starting or ending character or ASCII code.
  590. Note that if you want to specify a range that starts lower than 10, whatever
  591. reason should you have to do that, then you must supply a leading zero before
  592. the number so that it won't be a single character, as single characters supply
  593. their ASCII value even if they are numeric ('0' gives ASCII code 48).
  594. Examples:
  595. > SRename Data/ MT /160-,48-57 DELETE : Remove all characters with ASCII codes
  596. same as or greater than 160, and ASCII codes 48 to 57 (digit characters).
  597.  
  598. > SRename Data/ MT /-.,0-9,~- TO _ : Replace with '_' all characters before '.'
  599. including it, from '0' to '9', and after '~' including it.
  600.  
  601. Note that BEFORE and AFTER have no effect in single character and character
  602. code modes, and CASESENS has no effect in character code mode.
  603. If none of the above modes are active then normal string matches are performed.
  604. Multiple strings to match can be supplied by using '|' as a separator.
  605. The matching is case-insensitive by default unless CASESENS is also given,
  606. and the supplied string cannot be a wild-card.
  607.  
  608. The MATCH selector is very powerful and in conjunction with the DO, SKIP,
  609. BEFORE, AFTER and REVMATCH keywords which are used only with MATCH and are
  610. described below, and with the LEFT-MID-RIGHT selectors, it can select any part
  611. of the filename relative to the matched string.
  612. Using BEFORE or AFTER complicates things a bit for MATCH because selected
  613. character ranges can overlap, and changes in one selected range can affect the
  614. next selected range in the way that it will be selected and in the way it will
  615. be modified.
  616. To ensure that the intended characters by the user are selected, the MATCH
  617. selector corrects both the selected character range length and position.
  618. For example if two selected character ranges overlap, and new characters were
  619. inserted within the overlapping range, then the length of the second character
  620. range is adjusted so that all the intended characters are selected.
  621.  
  622. Examples:
  623. > SRename SYS: MT pic TO picture : Replace all occurrences of 'pic' with
  624. 'picture' in all the filenames in the root dir of SYS:
  625.  
  626. > SRename Work: MT exe|lib UP : Make every occurrence of 'exe' and 'lib'
  627. uppercase in all the filenames in the root dir of Work:
  628.  
  629. -------------------------------------------------------------------------------
  630.  
  631. DO <number of matches to perform> :
  632. Determines the maximum number of matches that will be attempted by the MATCH
  633. selector. The supplied numeric value should be at least 1, as a value of 0
  634. will not result in making no matches.
  635.  
  636. Example:
  637. > SRename -new-text-file MT - TO _ DO 2: Only the first 2 occurrences of '-'
  638. will be replaced with '_'.
  639. output: -new-text-file renamed as _new_text-file
  640.  
  641. -------------------------------------------------------------------------------
  642.  
  643. SKIP (SK) <number of matches to skip> :
  644. Determines the number of matches that will be skipped before any matches can
  645. be performed.
  646.  
  647. Example:
  648. > SRename -new-text-file MT - TO _ SK 1: Only the occurrences of '-' after the
  649. first will be replaced.
  650. output: -new-text-file renamed as -new_text_file
  651.  
  652. -------------------------------------------------------------------------------
  653.  
  654. REVMATCH (RM) :
  655. Makes the matching process to start from the end of the filename, instead of
  656. the start.
  657.  
  658. Example:
  659. > SRename -new-text-file MT - DO 1 RM : Only the last occurrence of '-' will be
  660. replaced.
  661. output: -new-text-file renamed as -new-text_file
  662.  
  663. -------------------------------------------------------------------------------
  664.  
  665. BEFORE (BF) :
  666. Selects the characters before the matched string. If you want to select a
  667. limited amount of characters before a string, you should use the RIGHT selector.
  668. Note that if you use BEFORE without RIGHT to select all characters before the
  669. matched string, and start the match from the right with REVMATCH, only one
  670. match will be performed, even if more than one strings to match exist.
  671.  
  672. Examples:
  673. > SRename lastletter MT letter BF UP : Makes uppercase all characters before
  674. 'letter'.
  675. output: lastletter renamed as LASTletter
  676.  
  677. > SRename gamescreengrab MT grab BF R 6 UP : Makes uppercase 6 characters
  678. before 'grab'.
  679. output: gamescreengrab renamed as gameSCREENgrab
  680.  
  681. -------------------------------------------------------------------------------
  682.  
  683. AFTER (AF) :
  684. Selects the characters after the matched string. If you want to select a
  685. limited amount of characters after a string, you should use the LEFT selector.
  686. Note that if you use AFTER without LEFT and without REVMATCH to select all
  687. characters after the matched string, only one match will be performed, even if
  688. more than one strings to match exist.
  689.  
  690. Examples:
  691. > SRename lastletter MT last AF UP : The characters after 'last' will be made
  692. uppercase.
  693. output: lastletter renamed as lastLETTER
  694.  
  695. > SRename "the last ballad" MT " " AF L 1 UP : This is equivalent to uppercase
  696. after space, with the exception that it does not uppercase the first character.
  697. output: the last ballad renamed as the Last Ballad
  698.  
  699. > SRename readmenow MT read AF L 3,2 UP : Makes uppercase 3 characters after
  700. the end of 'read' plus 2 characters.
  701. output: readmenow renamed as readmeNOW
  702.  
  703. -------------------------------------------------------------------------------
  704.  
  705. LEFT (L) <number of chars>,[<left offset>] :
  706. Select characters from the left side of the filename.
  707.  
  708. MID (M) [<left offset>],[<right offset>] :
  709. Select characters using the distance from the left and right edge of the
  710. filename.
  711.  
  712. RIGHT (R) <number of chars>,[<right offset>] :
  713. Select characters from the right side of the filename.
  714.  
  715. Left/right offset specifies the number of characters from left/right to skip
  716. before selecting the number of characters given in the first parameter.
  717. Note that PREFIX/MAIN/SUFFIX are evaluated before LEFT/MID/RIGHT.
  718. This means that you cannot for example select the 8 rightmost characters of a
  719. file/dirname and then select the main component in them (if there is one).
  720.  
  721. For example: SRename newfilename.suf R 8 MA UP  would not select the characters
  722. 'name' but would rather select the characters 'filename' as MAIN is evaluated
  723. before RIGHT.
  724. Also if more than one component of a filename is selected, any specified
  725. actions will take place on the selected components separately.
  726.  
  727. For example: SRename 001.testpic.jpeg MA SU L 1 UP  would make uppercase the
  728. leftmost character in MAIN, and then in SUFFIX (001.Testpic.Jpeg) and not the
  729. leftmost character of MAIN and SUFFIX combined (001.Testpic.jpeg).
  730.  
  731. Examples:
  732. > SRename Libs:datatypes.library L 1 UP
  733. output: datatypes.library renamed as Datatypes.library
  734.  
  735. > SRename Work:001picture R 1,6 UP
  736. output: 001picture renamed as 001Picture
  737.  
  738. > SRename DataPartition_backup M 4,7 Volume
  739. output: DataPartition_backup renamed as DataVolume_backup
  740.  
  741.  
  742. *******************************************************************************
  743.                OTHER KEYWORDS THAT AFFECT COMPONENT SELECTION:
  744. *******************************************************************************
  745.  
  746. EXCLUDE (XC) :
  747. Don't modify the selected characters but those that haven't been selected.
  748. Note that it does not invert the selection that has been made by the PREFIX/
  749. MAIN/SUFFIX selectors, and that it makes the exclusion after all the selectors
  750. that have been given have acted.
  751. If for example you have used the WORD and MATCH selectors and EXCLUDE, then
  752. you can't exclude a part with WORD and then act on the excluded parts with
  753. MATCH, because EXCLUDE will act after both WORD and MATCH will have selected
  754. some parts of the filename.
  755. Also note that when EXCLUDE is given with MATCH in single character or in
  756. character code mode, then the parts that are excluded are modified as single
  757. characters rather than as strings.
  758.  
  759. Examples:
  760. > SRename asmallfile MT small UP XC
  761. output: asmallfile renamed as AsmallFILE
  762.  
  763. > SRename editorprefs L 6 UP XC
  764. output: editorprefs renamed as editorPREFS
  765.  
  766. -------------------------------------------------------------------------------
  767.  
  768. CASESENS (CS) :
  769. Make string matching case-sensitive. The default is case insensitive.
  770. This keyword can be used in conjunction with the MATCH selector,the UPDATE
  771. action, and any of the renumbering actions.
  772. Refer to these keywords for a detailed description.
  773.  
  774. Example:
  775. > SRename FileNamewithname MT name TO Comment CS
  776. output: FileNamewithname renamed as FileNamewithComment
  777.  
  778. Note that only the second occurrence of 'name' is replaced with 'Comment'
  779. because the string matching is case-sensitive.
  780.  
  781. -------------------------------------------------------------------------------
  782.  
  783. EXIST (XS) :
  784. Modify the specified component (PREFIX-MAIN-SUFFIX) only if it exists.
  785.  
  786. Example:
  787. > SRename SoundSample SU TO 8SVX XS
  788. output: SoundSample not changed
  789.  
  790. A new suffix is not appended to the filename because it didn't have one in the
  791. first place.
  792.  
  793. -------------------------------------------------------------------------------
  794.  
  795. DOT <character> :
  796. Redefine the separator character. The default separator is a period (.)
  797. The separator character determines the PREFIX-MAIN-SUFFIX components.
  798.  
  799. Example:
  800. > SRename archive_tar_gz MA SU UP DOT _
  801. output: archive_tar_gz renamed as archive_TAR_GZ
  802.  
  803.  
  804. *******************************************************************************
  805.                               ACTION KEYWORDS:
  806. *******************************************************************************
  807.  
  808. The following keywords define how the characters that have been selected with
  809. the component selector keywords, will be modified.
  810.  
  811.  
  812. TO (AS) <[path/]filename> :
  813. Replaces the selected portion of the filename with the given string.
  814. It can also be used to move files to other directories in the same volume
  815. (AmigaOS Rename function limitation) if a path is supplied.
  816. The 'TO' keyword need not be given if no other action keywords are supplied,
  817. because in such a case the last given filename activates the 'TO' action.
  818. That means that now SRename can perform simple renaming in the same manner
  819. as the original Rename command:
  820.  
  821. > SRename oldfilename newfilename : 'oldfilename' is renamed as 'newfilename'.
  822.  
  823. If however you want for example to move a file to another directory and make
  824. it uppercase, then you will have to use 'TO' as:
  825.  
  826. > SRename anyfile TO dirx/ UP : 'anyfile' is moved to 'dirx' and is made
  827. uppercase.
  828.  
  829. If you omit 'TO' as: 'SRename anyfile dirx/ UP' ,that will tell SRename
  830. to make uppercase 'anyfile' and all the filenames in the directory 'dirx'.
  831.  
  832. Note that the destination path is inherited from the source path (if it was
  833. given) so that it (the destination path) doesn't have to be supplied with the
  834. new filename.
  835. For example if the current dir is not 'SYS:Data', to rename 'letter.txt' with
  836. the original Rename command you would type:
  837. > Rename SYS:Data/letter.txt SYS:Data/NewFileName
  838.  
  839. With SRename you just type:
  840. > SRename SYS:Data/letter.txt NewFileName.
  841.  
  842. Examples:
  843. > SRename SYS:OldFileName L 3 New
  844. output: OldFileName renamed as NewFileName
  845.  
  846. > SRename SYS:OldFileName SYS:C/ : Moves OldFileName to C: maintaining its
  847. filename.
  848.  
  849. > SRename SYS:OldFileName SYS:C/NewName : Moves OldFileName to C: and
  850. renames it as 'NewName'.
  851.  
  852. -------------------------------------------------------------------------------
  853.  
  854. UPPER (UP) :
  855. Makes the selected characters uppercase. It is Keymap sensitive so that it will
  856. function correctly with any keymap-font setup.
  857.  
  858. Example:
  859. > SRename Data/ L 1 UP : Makes uppercase the first character of every filename
  860. in 'Data'.
  861.  
  862. > SRename Data/ SU UP : Makes uppercase only the suffix of every filename in
  863. 'Data'.
  864.  
  865. -------------------------------------------------------------------------------
  866.  
  867. LOWER (LW) :
  868. Makes the selected characters lowercase. It is Keymap sensitive so that it will
  869. function correctly with any keymap-font setup.
  870.  
  871. Example:
  872. > SRename Data/TEXTFILE LW
  873. output: TEXTFILE renamed as textfile
  874.  
  875. -------------------------------------------------------------------------------
  876.  
  877. UPAFTERSPC (US) :
  878. Makes characters after spaces uppercase. It also makes uppercase the first
  879. character in the selected range.
  880.  
  881. Example:
  882. > SRename "Data/text file" US
  883. output: text file renamed as Text File
  884.  
  885. -------------------------------------------------------------------------------
  886.  
  887. INSERT (IN) <string> :
  888. Inserts the given string at the beginning of the selected characters.
  889. You can make the insertion anywhere within the filename by using the AT
  890. keyword, or at the end of the filename by using the APPEND keyword.
  891.  
  892. Example:
  893. > SRename Letter.txt IN First
  894. output: Letter.txt renamed as FirstLetter.txt
  895.  
  896. -------------------------------------------------------------------------------
  897.  
  898. AT <number of characters from left/right> :
  899. Determines the position within the filename at which the string that was given
  900. with INSERT, is to be placed.
  901. Note that in INSERT mode there always has to be at least one character after
  902. the string to be inserted, and in APPEND mode at least one character before the
  903. string to be appended.
  904. You can't for example insert string 'ABC' at the end of filename 'somefile'
  905. with :
  906. > SRename somefile IN ABC AT 8
  907. output: somefile not changed
  908.  
  909. To do the former you must use the APPEND action together with INSERT and AT.
  910. If the position you have specified is invalid for INSERT or APPEND, the
  911. operation will be aborted.
  912. Note that the AT keyword can also be used in renumbering mode to set the
  913. position of the number within the basename.
  914.  
  915. Example:
  916. > SRename AnyFilename IN XYZ AT 3
  917. output : AnyFilename renamed as AnyXYZFilename
  918.  
  919. -------------------------------------------------------------------------------
  920.  
  921. APPEND (AP) :
  922. Makes INSERT place the supplied string at the end of the selected characters,
  923. so make sure you supply the INSERT action too.
  924. Can also be used in conjunction with AT to determine the position
  925. of the inserted string not from the left but from the right of the selected
  926. characters.
  927. Note that the APPEND keyword can also be used in renumbering mode to set the
  928. position of the number within the basename.
  929.  
  930. Examples:
  931. > SRename Sound IN Sample AP
  932. output : Sound renamed as SoundSample
  933.  
  934. > SRename Sound.iff IN Sample AT 4 AP
  935. output : Sound.iff renamed as SoundSample.iff
  936.  
  937. -------------------------------------------------------------------------------
  938.  
  939. UPDATE (UD) :
  940. Allows the INSERT action to proceed only if the string to insert does not exist
  941. in the specified position.
  942. The characters that are compared with the string to insert, are after the
  943. specified position in insert mode and before the specified position in append
  944. mode. The comparison is case-insensitive unless CASESENS is given.
  945.  
  946. Examples:
  947. > SRename old_letter.txt IN Old UD : Because 'old' already exists in the
  948. beginning of the filename it is not inserted.
  949. output : old_letter.txt not changed
  950.  
  951. > SRename old_letter.txt IN Old UD CS : Now 'Old' is inserted because the
  952. comparison is case-sensitive.
  953. output : old_letter.txt renamed as Oldold_letter.txt
  954.  
  955. > SRename pic_last.iff IN Last AT 4 AP UD : Trying to insert 'last' 4 chars
  956. from the end fails because it already exists.
  957. output : pic_last.iff not changed
  958.  
  959. -------------------------------------------------------------------------------
  960.  
  961. DELETE (DL) :
  962. Removes the selected characters from the filename.
  963.  
  964. Examples:
  965. > SRename SYS: L 3 DL : deletes the first 3 characters from filenames in SYS:
  966.  
  967. > SRename SYS: SU DL : deletes the suffix from filenames in SYS:
  968.  
  969. > SRename SYS: MT :#@ DL : deletes every '#' and '@' character from filenames
  970. in SYS:
  971.  
  972. -------------------------------------------------------------------------------
  973.  
  974. SWAP (SW) :
  975. Swaps the selected filename components. If 2 of the PREFIX,MAIN,SUFFIX
  976. selectors are given, then the parts specified by these selectors will be
  977. swapped. Otherwise if none of the above selectors are given, or just one, or
  978. all of them, then just the 2 extremest components are swapped.
  979. SWAP has an effect only on filenames with at least 2 components, like prefix-
  980. main, main-suffix, or all (prefix-main-suffix).
  981.  
  982. Examples:
  983. > SRename picture.iff SW
  984. output: picture.iff renamed as iff.picture
  985.  
  986. > SRename 001.picture.iff SW
  987. output: 001.picture.iff renamed as iff.picture.001
  988.  
  989. > SRename 001.picture.iff PR MA SW
  990. output: 001.picture.iff renamed as picture.001.iff
  991.  
  992. -------------------------------------------------------------------------------
  993.  
  994. LSHIFT (LS) :
  995. Shifts the filename components to the left, the leftmost becomes the rightmost.
  996. Like SWAP it has an effect only on filenames with at least 2 components.
  997. This keyword operates on the whole filename, so the component selectors have
  998. no effect with it.
  999.  
  1000. Example:
  1001. > SRename SYS:001.picture.iff LS
  1002. output: 001.picture.iff renamed as picture.iff.001
  1003.  
  1004. -------------------------------------------------------------------------------
  1005.  
  1006. RSHIFT (RS) :
  1007. The opposite of LSHIFT. The rightmost component becomes the leftmost.
  1008.  
  1009. Example:
  1010. > SRename SYS:001.picture.iff RS
  1011. output: 001.picture.iff renamed as iff.001.picture
  1012.  
  1013.  
  1014. -------------------------------------------------------------------------------
  1015.  
  1016. UNIFY (UN) :
  1017. Unifies the filename components specified by PREFIX/MAIN/SUFFIX by deleting the
  1018. separator character. If no component is specified then it unifies the whole
  1019. filename.
  1020.  
  1021. Examples:
  1022. > SRename SYS:picture.001 UN
  1023. output: picture.001 renamed as picture001
  1024.  
  1025. > SRename SYS:001.picture.iff UN PR
  1026. output: 001.picture.iff renamed as 001picture.iff
  1027.  
  1028. > SRename SYS:001.some.complex.name.iff UN MA
  1029. output: 001.some.complex.name.iff renamed as 001.somecomplexname.iff
  1030.  
  1031. -------------------------------------------------------------------------------
  1032.  
  1033. CONV8+3 (8+3) :
  1034. Converts filenames to the MS DOS format of 8+3 characters. The filename will be
  1035. made uppercase, if it has a suffix this will be cut to 3 characters in length,
  1036. and if it has a prefix it will only be maintained if there is room left from
  1037. the main component.
  1038. Note that none of the selector keywords have any effect with this keyword,
  1039. because it always operates on the whole filename.
  1040. It is possible when converting whole directories that some filenames will fail
  1041. to be converted because they may get the same name with other files.
  1042. For example picture-1.iff and picture-2.iff will both receive the name:
  1043. PICTURE-.IFF
  1044.  
  1045. Examples:
  1046. > SRename SYS:User.prefs 8+3
  1047. output: User.prefs renamed as USER.PRE
  1048.  
  1049. > SRename SYS:sound.sample.iff 8+3
  1050. output: sound.sample.iff renamed as S_SAMPLE.IFF
  1051.  
  1052.  
  1053. *******************************************************************************
  1054.                                  RENUMBERING:
  1055. *******************************************************************************
  1056.  
  1057. SRename can perform intelligent renumbering of filename sequences in one go.
  1058. It is not limited in the formats it can support, as it scans the filenames for
  1059. numbers of up to 9 digits long, which can have leading zeros, and can be in
  1060. any position in the filename, or on their own.
  1061. You don't have to specify the order of renaming, normal or reverse, as with
  1062. other renumbering utilities, because it scans the filenames in the directory and
  1063. decides which way to go.
  1064. Furthermore you don't have to worry for filename clashes during renumbering,
  1065. as any clashes will be found before the actual renaming begins, and the
  1066. clashing filenames will be given temporary names, before are finally renamed.
  1067. Inverting the numbers in a sequence can also be performed, a feature that would
  1068. be useful in compiling ping-pong animations.
  1069.  
  1070. The following keywords are relevant to renumbering and can be given all at
  1071. once, or on their own :
  1072.  
  1073.  
  1074. RENUMBER (RN) <new starting number> :
  1075. Specifies the new starting number of a filename sequence. All matching
  1076. filenames will be renumbered unless an ending number is specified with UPTO.
  1077.  
  1078. Examples:
  1079. > SRename Data:picture001 RN 50 : will renumber all filenames that begin with
  1080. 'picture' and have a number attached at the end, to values starting with 50.
  1081. The leading zeros will be preserved.
  1082. output:
  1083. picture001 renamed as picture050
  1084. picture002 renamed as picture051
  1085. picture003 renamed as picture052
  1086. picture004 renamed as picture053
  1087. picture005 renamed as picture054
  1088.  ....
  1089.  
  1090. > SRename Data:picture001 RN 50 UT 4 : as above but will renumber up to
  1091. filename 'picture004'.
  1092. output:
  1093. picture001 renamed as picture050
  1094. picture002 renamed as picture051
  1095. picture003 renamed as picture052
  1096. picture004 renamed as picture053
  1097.  
  1098. > SRename Data:10.frame RN 020 : will renumber all filenames that end in
  1099. '.frame' and are preceded with a value of 10 or greater, to values starting
  1100. with 020.
  1101. output:
  1102. 10.frame renamed as 020.frame
  1103. 11.frame renamed as 021.frame
  1104. 12.frame renamed as 022.frame
  1105. 13.frame renamed as 023.frame
  1106. 14.frame renamed as 024.frame
  1107.  ....
  1108. Note that when you supply a new starting number with leading zeros,
  1109. the old number format is overridden.
  1110.  
  1111. -------------------------------------------------------------------------------
  1112.  
  1113. UPTO (UT) <renumber up to this number> :
  1114. Specifies the existing number in a filename up to which SRename will perform
  1115. any of the renumbering actions.
  1116. If you give this keyword you must specify at least one renumber-type action
  1117. (RENUMBER,STEP,PLACES,BASENAME,AT,INVERT) with it, otherwise a 'Required
  1118. argument missing' error will occur.
  1119.  
  1120. Examples:
  1121. > SRename Data:picture001 RN 50 UT 6 : will renumber from 'picture001' up to
  1122. 'picture006'.
  1123.  
  1124. > SRename Data:frame100 UT 110 BN AnimFrame : will change the basename to
  1125. 'AnimFrame' from 'frame100' up to 'frame110'.
  1126.  
  1127. > SRename Pics/datafile0010 UT 20 PL 2 : will make 2-digit the numbers from
  1128. 'datafile0010' up to 'datafile0020'.
  1129.  
  1130. -------------------------------------------------------------------------------
  1131.  
  1132. STEP (ST) <step value> :
  1133. Defines the increment value of renumbering. The default increment is 1.
  1134. It can also take negative values.
  1135.  
  1136. Examples:
  1137. > SRename Data:picture001 RN 30 ST 2 : increases the new starting value by 2.
  1138. output:
  1139. picture001 renamed as picture030
  1140. picture002 renamed as picture032
  1141. picture003 renamed as picture034
  1142. picture004 renamed as picture036
  1143.  ....
  1144.  
  1145. > SRename Data:picture001 ST 3 : will keep the original starting value, but
  1146. will increase the destination numbers in steps of 3 :
  1147. output:
  1148. picture004 renamed as picture010
  1149. picture003 renamed as picture007
  1150. picture002 renamed as picture004
  1151. picture001 not changed
  1152.  ....
  1153. Note that the renumbering is executed in reverse order in order to avoid a
  1154. clash when renaming picture002 to picture004 (picture004 already exists).
  1155.  
  1156. -------------------------------------------------------------------------------
  1157.  
  1158. PLACES (PL) <places value> :
  1159. Sets the number format of the destination filenames. This affects the number of
  1160. leading zeros the numbers will have.
  1161. If you specify a places value that is smaller than the digits a number already
  1162. has, that number will be unaffected. Any numbers will less digits than the
  1163. places value will be padded with leading zeros.
  1164.  
  1165. Examples:
  1166. > SRename Data:picture001 RN 30 PL 4 : makes the numbers 4-digit.
  1167. output:
  1168. picture001 renamed as picture0030
  1169. picture002 renamed as picture0031
  1170. picture003 renamed as picture0032
  1171. picture004 renamed as picture0033
  1172.  ....
  1173.  
  1174. > SRename Data:picture001 PL 1 : strips all leading zeros from the numbers.
  1175. output:
  1176. picture001 renamed as picture1
  1177. picture002 renamed as picture2
  1178. picture003 renamed as picture3
  1179. picture004 renamed as picture4
  1180.  ....
  1181.  
  1182. > SRename Data:picture001 UT 3 PL 2 : will renumber from number 001 to 003,
  1183. and make the numbers 2-digit.
  1184. output:
  1185. picture001 renamed as picture01
  1186. picture002 renamed as picture02
  1187. picture003 renamed as picture03
  1188.  
  1189. -------------------------------------------------------------------------------
  1190.  
  1191. INVERT (IV) :
  1192. Invert the numbers in a filename sequence. This is exactly how inverting works:
  1193.  
  1194.          original filenames              new filenames
  1195.          ------------------              -------------
  1196.             file.10        -> becomes ->   file.14
  1197.             file.11        -> becomes ->   file.13
  1198.             file.12       - not changed -
  1199.             file.13        -> becomes ->   file.11
  1200.             file.14        -> becomes ->   file.10
  1201.  
  1202. You may have noticed that executing this sequence of rename commands has a
  1203. problem: how can 'file.10' become 'file.14' when 'file.14' already exists.
  1204. SRename sees that and when destination filenames already exist, the files to
  1205. be renumbered are given temporary filenames until the existing filenames
  1206. themselves have been renumbered, so after this is done the temporary filenames
  1207. are given their normal destination filenames.
  1208. An unresolvable error occurs (New number exists) if these existing filenames
  1209. that cause clashes are not scheduled to be renumbered because they are outside
  1210. the range of files to be renumbered.
  1211.  
  1212. Examples:
  1213. > SRename Data:file100 IV : inverts the whole filename sequence.
  1214. output:
  1215. file100 renamed as 109.srtemp861A5BC
  1216. file101 renamed as 108.srtemp861A5BC
  1217. file102 renamed as 107.srtemp861A5BC
  1218. file103 renamed as 106.srtemp861A5BC
  1219. file104 renamed as 105.srtemp861A5BC
  1220. file105 renamed as file104
  1221. file106 renamed as file103
  1222. file107 renamed as file102
  1223. file108 renamed as file101
  1224. file109 renamed as file100
  1225. 109.srtemp861A5BC renamed as file109
  1226. 108.srtemp861A5BC renamed as file108
  1227. 107.srtemp861A5BC renamed as file107
  1228. 106.srtemp861A5BC renamed as file106
  1229. 105.srtemp861A5BC renamed as file105
  1230.  
  1231. Notice how numbers 100 to 104 are given temporary filenames before been finally
  1232. renumbered, because of clashes that would occur during the renaming process.
  1233.  
  1234. > SRename Data:file100 RN 50 IV : inverts the filename sequence and gives it
  1235. a starting number of 50.
  1236. output:
  1237. file100 renamed as file59
  1238. file101 renamed as file58
  1239. file102 renamed as file57
  1240. file103 renamed as file56
  1241. file104 renamed as file55
  1242. file105 renamed as file54
  1243. file106 renamed as file53
  1244. file107 renamed as file52
  1245. file108 renamed as file51
  1246. file109 renamed as file50
  1247.  
  1248. -------------------------------------------------------------------------------
  1249.  
  1250. BASENAME (BN) <basename string> :
  1251. Changes the filenames of a sequence but leaves the numbers that are attached
  1252. to each filename intact.
  1253. To delete the basename of a filename sequence, thus leaving only the numbers,
  1254. you should simply give: BASENAME ""
  1255.  
  1256. Examples:
  1257. > SRename Data:file100 BN picture : replaces 'file' with 'picture' in every
  1258. filename. Note that the number continues to be at the end of the new basename.
  1259. output:
  1260. file100 renamed as picture100
  1261. file101 renamed as picture101
  1262. file102 renamed as picture102
  1263. file103 renamed as picture103
  1264.  ....
  1265.  
  1266. > SRename Data:sound001.iff BN snd : will replace 'sound' with 'snd'.
  1267. output:
  1268. sound001.iff renamed as snd001
  1269. sound002.iff renamed as snd002
  1270. sound003.iff renamed as snd003
  1271. sound004.iff renamed as snd004
  1272.  ....
  1273.  
  1274. > SRename Data:file001pic RN 50 BN filepicture : will renumber starting at 50,
  1275. and replace 'filepic' with 'filepicture'. Note that the old number position
  1276. is preserved.
  1277. output:
  1278. file001pic renamed as file50picture
  1279. file002pic renamed as file51picture
  1280. file003pic renamed as file52picture
  1281. file004pic renamed as file53picture
  1282.  ....
  1283.  
  1284. > SRename Data:file001pic BN "" : will delete the basename.
  1285. output:
  1286. file001pic renamed as 001
  1287. file002pic renamed as 002
  1288. file003pic renamed as 003
  1289. file004pic renamed as 004
  1290.  ....
  1291.  
  1292. Note that when the number is surrounded by the basename, (the number is not
  1293. at the beginning or at the end) the position of the number within the basename
  1294. is preserved when a new basename is given. This position can be changed with
  1295. the use of the AT and/or APPEND keywords as we will see later.
  1296.  
  1297. -------------------------------------------------------------------------------
  1298.  
  1299. AT <position value> :
  1300. Sets the position of the number within the basename.
  1301.  
  1302. Examples:
  1303. > SRename frame100.iff AT 0 : will move all numbers in the filename sequence
  1304. 0 characters from the left.
  1305. output:
  1306. frame100.iff renamed as 100frame.iff
  1307. frame101.iff renamed as 101frame.iff
  1308. frame102.iff renamed as 102frame.iff
  1309. frame103.iff renamed as 103frame.iff
  1310.  ....
  1311.  
  1312. > SRename 100frame.iff AT 5 : will move all numbers 5 characters from the left.
  1313. output:
  1314. 100frame.iff renamed as frame100.iff
  1315. 101frame.iff renamed as frame101.iff
  1316. 102frame.iff renamed as frame102.iff
  1317. 103frame.iff renamed as frame103.iff
  1318.  ....
  1319.  
  1320. -------------------------------------------------------------------------------
  1321.  
  1322. APPEND (AP) :
  1323. Sets alone or in conjunction with AT the position of the number within the
  1324. basename. When used alone the numbers go at the end of the basename, and when
  1325. used with AT, the position is measured from the end of the basename.
  1326.  
  1327. Examples:
  1328. >SRename frame100.iff AP : all numbers will be moved at the end of the basename.
  1329. output:
  1330. frame100.iff renamed as frame.iff100
  1331. frame101.iff renamed as frame.iff101
  1332. frame102.iff renamed as frame.iff102
  1333. frame103.iff renamed as frame.iff103
  1334.  ....
  1335.  
  1336. >SRename 100frame.iff AT 4 AP : all numbers will be moved 4 characters from the
  1337. end of the basename.
  1338. output:
  1339. 100frame.iff renamed as frame100.iff
  1340. 101frame.iff renamed as frame101.iff
  1341. 102frame.iff renamed as frame102.iff
  1342. 103frame.iff renamed as frame103.iff
  1343.  ....
  1344.  
  1345. -------------------------------------------------------------------------------
  1346.  
  1347. CASESENS (CS) :
  1348. When in renumbering mode, preserves each basename's casing. If CASESENS is not
  1349. given, all basenames will get their content from the first basename that is to
  1350. be renumbered.
  1351.  
  1352. Example:
  1353. >SRename frame01 RN 20 CS
  1354. output:
  1355. frame01 renamed as frame20
  1356. FRAME02 renamed as FRAME21
  1357. frame03 renamed as frame22
  1358. FRAME04 renamed as FRAME23
  1359. frame05 renamed as frame24
  1360.  
  1361. As you see the second and fourth basename remain in upper case.
  1362.  
  1363. *******************************************************************************
  1364.                                OTHER KEYWORDS:
  1365. *******************************************************************************
  1366.  
  1367. NODIROUT (NDO) :
  1368. Suppresses directory name output during recursion.
  1369.  
  1370. QUIET (Q) :
  1371. Suppresses all output including error messages.
  1372.  
  1373. -------------------------------------------------------------------------------
  1374.  
  1375.  
  1376. EMULATED FUNCTIONS :
  1377.  
  1378. You may think that SRename has some functions missing, like uppercase first
  1379. character, delete spaces, spaces to underscores, replace string1 with string2,
  1380. etc.
  1381. Such specialised functions can be built with other functions, for example:
  1382. Uppercase first can be performed with: LEFT 1 UP, delete spaces with: MATCH " "
  1383. DELETE, spaces to underscores with MATCH " " TO _ , and replace str1 with str2
  1384. with MATCH string1 TO string2.
  1385. Even uppercase after space can be emulated with MATCH " " AFTER LEFT 1 UP, but
  1386. as the emulated function does not uppercase the first character too, I have
  1387. left the specialised function in.
  1388.  
  1389.  
  1390. PRIORITIES :
  1391.  
  1392. Not all keyword combinations make sense, that's why some keywords have priority
  1393. or cancel others. The following priorities exist:
  1394.  
  1395. LEFT has priority over MID which has priority over RIGHT
  1396. MATCH is evaluated before LEFT/MID/RIGHT
  1397. WORD is evaluated before MATCH
  1398. NODIRS cancels NOFILES
  1399. BEFORE cancels AFTER
  1400. RLEVEL has priority over RECURSE
  1401. DELETE cancels every other action
  1402. TO cancels every other action except DELETE
  1403. CONV8+3 cancels UPPER, LOWER and UPAFTERSPC
  1404. UPPER cancels LOWER and UPAFTERSPC
  1405. LSHIFT cancels RSHIFT
  1406. Any renumbering related action is cancelled by any other non-renumbering action.
  1407.  
  1408.  
  1409. TIPS:
  1410.  
  1411. When you use SRename with a filemanager like Directory Opus, and you have set
  1412. it up to receive multiple filenames ({O} option in DOpus), place that option
  1413. at the end of the command line, because if the filename sequence is too big
  1414. the arguments after it will be omitted. For example don't give DOpus the
  1415. command SRename {O} UP QUIET, but SRename UP QUIET {O}.
  1416.  
  1417. Since SRename has no way of knowing the maximum filename length that each
  1418. filesystem allows, care must be taken by the user not to supply longer
  1419. filenames than the filesystem can handle, so that filename clashes won't occur.
  1420.  
  1421. Although SRename can work with filenames that contain wildcard characters
  1422. (i.e. parentheses) and thus are recognised by the OS as file matching patterns,
  1423. it will only rename such filenames if it can find them immediately in the
  1424. supplied path.
  1425. It is not possible for example to specify such a filename and tell SRename to
  1426. recurse through the directory tree, renaming every occurrence of this filename,
  1427. if it does not find it in the starting directory, because once it can't find it
  1428. it will decide that it's a file-matching pattern, which is not what it was
  1429. intended for by you.
  1430. I advise that such filenames that confuse the OS and other applications are
  1431. not used.
  1432.  
  1433. Even if the command interface is 100% compatible with the original rename
  1434. command (version 37.2), SRename still differs in the way that it inherits
  1435. the destination path from the supplied source path.
  1436. For that reason I don't recommend that you replace the original Rename command
  1437. with SRename.
  1438.  
  1439.  
  1440. LIMITATIONS :
  1441.  
  1442. - Because of the way that the ReadArgs OS function works, you can not assign
  1443. different actions to different parts of the filename in one go, like for
  1444. example SRename anyfilename.suffix LEFT 3 UP SUFFIX DELETE.
  1445. The previous command will just delete the 3 leftmost characters from the
  1446. suffix (DELETE cancels UP).
  1447. This will change in the future.
  1448.  
  1449. - When recursing, it can go up to 255 directory levels deep (it's difficult to
  1450. encounter even 10 levels of depth).
  1451.  
  1452. - Recursing is cancelled if a destination path is given.
  1453.  
  1454. - The path of a file can't be longer than 1024 characters.
  1455.  
  1456.  
  1457. Limitations in Renumbering:
  1458.  
  1459. - Numbers in filenames from 0 to 999999999 can be handled.
  1460.  
  1461. - No wildcards can be used, and when a destination path is supplied no clash-
  1462. checking takes place (it is assumed that the destination directory contains
  1463. no filenames that can clash with the filenames that will be moved there).
  1464.  
  1465. - No filenames that contain wildcard characters can be used, because pattern-
  1466. matching is used to collect the filenames of the sequence.
  1467.  
  1468. - Any numbers that have a different format to that of the first number scanned
  1469. will not be renumbered: if the first number is 001 and 02,03 follow, these
  1470. will not be renumbered because SRename will try to find 002 and 003.
  1471.  
  1472. - None of the selector keywords have any effect in renumbering mode.
  1473.  
  1474. - A filename clash can not be resolved if the clashing filename is outside the
  1475. range of filenames to be renumbered ('New number exists' error).
  1476.  
  1477.  
  1478. KNOWN BUGS :
  1479.  
  1480. SRename allows you to use long filenames even on filesystems that don't
  1481. support them (like FFS), so on such filesystems filenames longer than the
  1482. maximum allowed length (30 characters on FFS) will be trimmed by the
  1483. filesystem itself.
  1484.  
  1485. Although the MATCH selector performs length and position correction for the
  1486. selected character range, in case of overlapping ranges, actions that accept
  1487. position parameters are not corrected.
  1488.  
  1489.  
  1490. THANKS :
  1491.  
  1492. Special thanks to Bill Duxbury who informed me of the button bank problems
  1493. with DOpus Magellan and helped me make a button bank suitable for that version
  1494. of DOpus, and also for doing beta-testing.
  1495. Thanks also to all the people who have sent emails.
  1496.  
  1497.  
  1498. HISTORY :
  1499.  
  1500. Version                               Changes
  1501. ------- -----------------------------------------------------------------------
  1502.  
  1503. 2.500 : First Aminet release.
  1504.         Added BEFORE,AFTER,REVMATCH options for MATCH selector.
  1505.         Added UPDATE option for INSERT action.
  1506.         Major interface changes: removed additional parameters from MATCH,
  1507.         INSERT and RENUMBER and made them separate, also changed the full names
  1508.         of LEN,PRE,SUF and gave abbreviations to PREFIX,MAIN,SUFFIX,LEFT,MID,
  1509.         RIGHT and QUIET.
  1510.         AT is now used for number positioning in renumbering instead of
  1511.         LEFT and RIGHT.
  1512.         Removed the DELBASE action.
  1513.         Fixed bug in TO action.
  1514.         Can now rename filenames that are recognised by the OS as wildcards
  1515.         if these filenames are found in the given path.
  1516.         Fixed bugs introduced in 2.430 that caused misrecognition of same
  1517.         source and destination filenames.
  1518.  
  1519. 2.510 : Added ICONS option for automatic icon renaming.
  1520.         Fixed a bug in routine that detects same source-destination filename.
  1521.  
  1522. 2.520 : The TO keyword is now optional for some rename actions.
  1523.         The FILENAME keyword was renamed as FROM.
  1524.         Fixed serious bug that hampered multiple filepattern renaming when
  1525.         different directories were given.
  1526.         Improved the error and other message output.
  1527.         Errors: 'source path not found', 'no number in filename' and
  1528.         'invalid number in filename' do not abort the processing of other
  1529.         filepatterns anymore.
  1530.         Some code optimizations.
  1531.  
  1532. 2.530 : Changed the way that temporary filenames are named when resolving
  1533.         clashes, to eliminate the possibility that another SRename task could
  1534.         use the same temporary filenames when trying to resolve a clash.
  1535.         Now all temporary filenames receive an address that is different
  1536.         for each SRename task.
  1537.         As a result the limit for numbers contained in filenames has gone up
  1538.         to just under a billion (999999999).
  1539.         Failure to perform a temporary rename in renumbering mode now results
  1540.         in an error message and termination of further processing.
  1541.         Fixed small bug that caused the casing of the basename in renumbering
  1542.         to be determined from the given starting filename.
  1543.     Made a few code optimizations.
  1544.  
  1545. 2.540 : MATCH selector enhancements:
  1546.         * Added single character mode, as a result the DELCHARS action was
  1547.          removed, as it can be replaced by MATCH :<chars> DELETE.
  1548.         * Added character code mode supporting ranges.
  1549.         * MATCH can now accept multiple strings to match.
  1550.         The SWAP action can now swap the filename parts determined by the
  1551.         PREFIX/MAIN/SUFFIX selectors, instead of always swapping the two
  1552.         extreme parts.
  1553.         Increased the limit for maximum number of filenames in each directory
  1554.         to 32768 and of directory names to 4096.
  1555.         Some more optimizations for speed.
  1556.  
  1557. 2.600 : Now SRename supports filenames up to 120 characters long on filesystems
  1558.         that allow filenames longer than 30 characters (e.g. SFS)
  1559.         The real new filename is now printed after renaming, as the filesystem
  1560.         that is used can affect the final form of the filename.
  1561.         Small change in temporary filenames to aid renumbering on MS-DOS like
  1562.         filesystems.
  1563.  
  1564. 2.610 : Fixed long standing bug that resulted in higher memory usage than
  1565.         necessary in renumbering.
  1566.         Replaced sorting routine in renumbering with qsort.
  1567.         Some more optimizations in renumbering.
  1568.  
  1569. 2.700 : Added WORD selector and FROMEND,INCLSEP,WSEP support keywords.
  1570.         Removed LENGTH action as it can be performed by MID <len> DELETE.
  1571.         Fixed bugs with EXCLUDE. Now it performs consistently whatever the
  1572.         selected part of the filename is, and works correctly with multiple
  1573.         matches (MATCH selector).
  1574.         Fixed bug in renumbering. It wouldn't renumber single filenames if
  1575.         the number was in the beginning.
  1576.         Increased maximum allowed path to 1024 chars.
  1577.         Many structural and code optimizations.
  1578.  
  1579. 2.710 : Doh! EXCLUDE was still buggy. It didn't work at all with multiple
  1580.         strings to match so it's code was completely rewritten.
  1581.         Also fixed a bug with EXCLUDE and the single char mode or character
  1582.         code mode of the MATCH selector. Now if such a mode is active when
  1583.         EXCLUDE is given the excluded parts are modified as single characters
  1584.         instead of as character strings.
  1585.         Single char mode is automatically activated now if a single character
  1586.         is given with MATCH.
  1587.  
  1588. 2.800 : SRename is now re-entrant and can be made resident.
  1589.         Rewrote the paged buffer routines so that buffer overflows can't occur
  1590.         anymore, thus removing the limits on how many filenames can be renamed
  1591.         in one go.
  1592.         Fixed bug that occured when attempting to rename to an empty filename
  1593.         and the ICONS option was also given.
  1594.         Increased the maximum recursion limit from 127 to 255 levels.
  1595.         Improved the output of SRename somewhat.
  1596.         Optimized some renumbering routines and made many general code
  1597.         improvements.
  1598.         
  1599.  
  1600. If you use SRename or you have some suggestion, request, or bug report,
  1601. email me at: cnicol@compulink.gr
  1602.  
  1603. or for snail-mail:
  1604.  
  1605.  Constantinos Nicolakakis
  1606.  Olympion 7 Patissia
  1607.  11143 Athens, Greece
  1608.  
  1609.